home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 24 / CU Amiga Magazine's Super CD-ROM 24 (1998)(EMAP Images)(GB)(Track 1 of 2)[!][issue 1998-07].iso / CUCD / Programming / EasyPLUGINs / docs / dclistview.doc < prev    next >
Encoding:
Text File  |  1998-02-09  |  5.0 KB  |  115 lines
  1. DCListview PLUGIN
  2. -----------------
  3.  
  4. by Victor Ducedre <victord@netrover.com>
  5.  
  6.     This plugin creates a GadTools Listview gadget, almost identical to the
  7. standard EasyGUI one, except that it will also report double-clicks on list
  8. items.
  9.  
  10. Usage:
  11.  
  12.     [DCLIST, {actionfunction}, dc, TRUE]
  13.  
  14.     Notes:
  15.     -   Be sure the 'isgt' field of the PLUGIN gadget is always TRUE, since
  16.     this uses a GadTools gadget.
  17.     -   The DCLIST constant (which =PLUGIN) is available to be used in your
  18.     EasyGUI gadget list, as shown above.  This can make plugins in gadget lists
  19.     easier to identify, especially if you use a lot of different plugins.
  20.     -   Your action function will be called (or your action value returned by
  21.     easyguiA()) when:
  22.         -   an item is selected with the mouse, and again on a double click.
  23.         -   the assigned key is pressed, alone or shifted.
  24.         NOTE: if you use an action value instead of an action function, you
  25.         won't hear about double clicks since your GUI will have closed :-)
  26.  
  27. Methods:
  28.  
  29.     dclistview(tags)
  30.  
  31.           The constructor for this plugin, where 'tags' is a PTR TO a list of
  32.         tagitems from those listed below marked [I].  All values default to
  33.         something reasonable, so you can use simply [TAG_DONE] as your list.
  34.           You *must* open 'utility.library' prior to calling this function, or
  35.         it will raise a "util" exception.
  36.           This function has no return value.
  37.  
  38.     set(attr, val)
  39.  
  40.           Sets any attribute to the value given, where 'attr' is any item
  41.         listed below that is marked [S], and 'val' is some reasonable value
  42.         for said attribute.
  43.           This function has no return value, EXCEPT when setting DCLV_CURRENT
  44.         to a new value.  In this case it returns the value that DCLV_CURRENT
  45.         was actually set to, should you have tried to set it to a value that
  46.         was out of range.
  47.  
  48.     value, check:=get(attr)
  49.  
  50.           Gets the value for the specified attribute, where 'attr' is any item
  51.         listed below marked [G].  The second returned value, 'check', is TRUE
  52.         if 'attr' is in fact "getable", otherwise FALSE.
  53.  
  54.     END *must* be called for each NEWed object.
  55.  
  56. Possible attribute tags:
  57.  
  58.     DCLV_LABEL                        [I..]
  59.         The label which appears above the gadget.  Including a "_" in
  60.         this string will automatically assign the next character as the
  61.         keyboard shortcut, and will indicate it as such in the label.
  62.         (Default: No label text)
  63.     DCLV_RELX                         [I..]
  64.         The usual relative gadget width (Default: 5)
  65.     DCLV_RELY                         [I..]
  66.         The usual relative gadget height (Default: 5)
  67.     DCLV_LIST                         [ISG]
  68.         The list to be displayed in the gadget.  Usual gadtools handling
  69.         applies:  set to NIL to remove the list from the gadget, set to -1
  70.         to detach the list without clearing it. (Default: NIL)
  71.     DCLV_CURRENT                      [ISG]
  72.         The list item to be highlighted and placed at the top of the listview.
  73.         This item will also be displayed beneath the listview under v37 or
  74.         with a highlight bar under v39.  This value will always be updated
  75.         when the user selects a list item.
  76.     **  NOTE: If you don't want ANY list item highlighted initally, set
  77.         this tag to -1 (Default).  NOTE FURTHER, though, that the value of
  78.         this attribute will NOT change if the user does not manipulate the
  79.         listview in any way.  If you set DCLV_CURRENT to -1 at any point,
  80.         be prepared to properly handle -1 as a returned value when you
  81.         get(DCLV_CURRENT).
  82.     DCLV_DISABLED                     [ISG]
  83.         Whether this gadget is disabled.  Works under v39+ only, and is
  84.         minimal at best (the listview is disabled, but the attached prop
  85.         gadget will still scroll the list).  (Default: FALSE)
  86.     DCLV_TOP                          [ISG]
  87.         Sets which item in the list is to be diplayed at the top of the
  88.         listview, without necessarily being currently selected.
  89.     DCLV_CLICK                        [..G]
  90.         This will be set to TRUE when an item from the listview has been
  91.         double-clicked.
  92.  
  93. Exceptions:
  94.  
  95.     "dclv" will be raised by gtrender() if the gadget can't be created.
  96.     "util" will be raised by dclistview() if utility.library isn't open.
  97.  
  98. History:
  99.  
  100. 13-Jul-97  First release
  101.  
  102. 19-Aug-97  Second release
  103.            - removed a v39-only function that pretty much squashed the plugin
  104.              under v37.
  105.  
  106. 19-Jan-98  Third release
  107.            - rewritten in a style similar to the EasyPLUGINs Style Guide;
  108.            - replaced long list of constructor arguments with a taglist;
  109.            - replaced specific set#?/get#? functions with multi-purpose ones,
  110.              allowing many more attributes to be set/get with minimum effort,
  111.              and allowing the entire dclistview object to be made private;
  112.            - now checks if window and gadget exist (i.e., not iconified) before
  113.              updating attributes;
  114.            - simplified node-counter function;
  115.